home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 21 / Cream of the Crop 21 (Terry Blount) (October 1996).iso / bbs / develop.zip / PCBSYS.DOC < prev    next >
Text File  |  1996-07-23  |  11KB  |  221 lines
  1.   WARNING:  This document is subject to change at any time.  Any changes made
  2.   will be indicated by a vertical bar (|) in column 1 of the file.
  3.  
  4. | Last update: 07/23/96
  5.  
  6. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  7.  
  8.   The following file documents the format of the PCBOARD.SYS file including the
  9.   fields which have been standard throughout the PCBoard version 14.x series as
  10.   well as the new v15.0 software.
  11.  
  12.   The file may be written in one of two modes:  1) as a 128 byte file which is
  13.   compatible with the PCBoard v14.x series or 2) as a complete file including
  14.   all of the extensions added in the v14.5 release.
  15.  
  16.   In any case the file should be pre-filled with spaces inside the first 128
  17.   bytes so that any field not written is filled with spaces instead of zeroes
  18.   or other characters.  Typically this only really matters when a caller is not
  19.   online at which time only the first five fields inside of the 128 byte block
  20.   are valid.  The rest of the fields outside of the 128 byte block may contain
  21.   valid data or the file may be truncated to 128 bytes without serious loss of
  22.   data.
  23.  
  24.   As a door author wanting to provide LOGOFF PROCESSING in your door, what we
  25.   recommend is that you do NOT process the logoff yourself, but instead,
  26.   return to PCBoard and let PCBoard perform the logoff processing.  This is a
  27.   matter of convenience for you, since PCBoard can grow and change and you will
  28.   not need to modify your application whenever the logoff processing is
  29.   enhanced.  If you still wish to offer a GOODBYE command, what we recommend
  30.   is that you simply turn DTR off and then return back to PCBoard.  PCBoard
  31.   will then detect carrier loss and process the logoff for you.
  32.  
  33.   If you still want to perform the logoff processing yourself, here are a few
  34.   of the "current" details of what is necessary:
  35.  
  36.   1) You will need to empty the pcboard.sys file.  You do that by filling the
  37.      file, from offset 9 to offset 127, with spaces, leaving everything else
  38.      inside of the file intact.
  39.  
  40.   2) You will need to update the user record in the USERS file for the amount
  41.      of time spent online (don't forget to correctly calculate time used when
  42.      crossing midnight).
  43.  
  44.   3) If accounting is enabled, charge the caller for time used and write the
  45.      information to the account tracking file (in text format or dBase format
  46.      as appropriate to the extension of that file).
  47.  
  48.   4) Update the PCBSTATS.DAT file with the last caller information.
  49.  
  50.   5) Run the $$LOGOFF.BAT file if it exists.
  51.  
  52.   NOTE:  The above steps may change as PCBoard's features continue to be
  53.   enhanced.  In some ways, I hope the above set of steps appears daunting
  54.   enough to convince you to just let PCBoard do the logoff processing for you.
  55.   One more advantage is that, in doing so, that is one less thing for you to
  56.   have to do, and one less problem for you to figure out if it is done wrong.
  57.  
  58.   The following layout is specified in a "byte offset" format such that the
  59.   first field begins at offset 0.
  60.  
  61.   The following is a definition of the variable types that will be used below:
  62.  
  63.    char   = a 1 byte character
  64.    str    = an array of 2 or more "char" bytes
  65.    int    = a 2 byte integer
  66.    long   = a 4 byte long integer
  67.    bsreal = a 4 byte Basic Single Precision real number
  68.    bitmap = an array of bytes accessed a bit at a time
  69.  
  70.    Offset   Type   Length  Description
  71.    ------  ------  ------  -----------
  72.       0    str        2    Display On/Off ("-1" = On, " 0" = Off)
  73.       2    str        2    Printer On/Off ("-1" = On, " 0" = Off)
  74.       4    str        2    Page Bell On/Off ("-1" = On, " 0" = Off)
  75.       6    str        2    Caller Alarm On/Off ("-1" = On, " 0" = Off)
  76.       8    char       1    Sysop Flag (" ", "N"=sysop next, "X"=exit dos)
  77.       9    str        2    Error Corrected ("-1" = On, " 0" = Off)
  78.      11    char       1    Graphics Mode ('Y'=yes, 'N'=no, '7'=7E1)
  79.      12    char       1    Node Chat Status ('A'=available, 'U'=unavailable)
  80.      13    str        5    DTE Port Speed (PC to Modem speed)
  81.      18    str        5    Connect Speed shown to caller or "Local"
  82.      23    int        2    User's Record Number in the USERS file
  83.      25    str       15    User's First Name (padded to 15 characters)
  84.      40    str       12    User's Password (padded to 12 characters)
  85.      52    int        2    Time User Logged On (in minutes since midnight)
  86.      54    int        2    Time used so far today (negative number of minutes)
  87.      56    str        5    Time User Logged On (in "HH:MM" format)
  88.      61    int        2    Time Allowed On (from PWRD file) (see note 1 below)
  89.      63    int        2    Allowed K-Bytes for Download (see note 2 below)
  90.      65    char       1    Conference Area user was in (if <= 255)
  91.      66    bitmap     5    Conference Areas the user has joined this session
  92.      71    bitmap     5    Conference Areas the user has scanned this session
  93.      76    int        2    Conference Add Time in minutes
  94.      78    int        2    Upload/Sysop CHAT Credit Minutes (see note 3 below)
  95.      80    str        4    Language Extension (see note 4 below)
  96.      84    str       25    User's Full Name (padded to 25 characters)
  97.     109    int        2    Calculated Minutes Remaining (see note 5 below)
  98.     111    char       1    Node Number (or ' ' if no network)
  99.     112    str        5    Event Time (in "HH:MM" format, "00:00" if no event)
  100.     117    str        2    Is Event Active ("-1" = On, " 0" = Off) (see note 7)
  101.     119    str        2    Reserved (was Slide Event, no longer used here)
  102.     121    bsreal     4    Memorized Message Number
  103.     125    char       1    Comm Port Number (0=none, 1-8)
  104.     126    char       1    Reserved for PCBoard
  105.     127    bitmap     1    See Node 8 below for details
  106.     128    char       1    Use ANSI (1 = Yes, 0 = No)
  107.     129    int        2    Country Code
  108.     131    int        2    Code Page
  109.     133    char       1    YES character
  110.     134    char       1    NO character
  111.     135    char       1    Language 0=None, otherwise correspond with PCBML.DAT
  112.     136    char       3    RESERVED
  113.     139    char       1    Caller Exited to DOS (1 = Yes, 0 = No)
  114.     140    char       1    RESERVED (was Event Up Coming, no longer used)
  115.     141    char       1    Stop Uploads (1 = Yes, 0 = No)
  116.     142    int        2    Conference Area user was in (up to 65535)
  117.     144    bitmap  varies  High Conference Areas the user has joined (note 6)
  118.    varies  bitmap  varies  High Conference Areas the user has scanned (note 6)
  119.    varies  int        2    Node Number if offset 111 is set to 255, seek to
  120.                            the end of the file, minus 2, to read this value
  121. |  varies  long       4    When "big indexes" are in effect, it is possible
  122. |                          for the number of user records to go beyond 65535,
  123. |                          in which case, this field holds the real user
  124. |                          record number (in place of the 2 byte integer that
  125. |                          is found at offset 23).
  126.  
  127.   Note 1
  128.   ------
  129.   The "Time Allowed On" field is not the calculated allowed time remaining.
  130.   The user's record in the USERS file is not updated with the "Last Date On" or
  131.   "Elapsed Time On" information so far that day before the program exits to
  132.   either perform a DOS function or run a DOOR program.  DOOR programs,
  133.   therefore, should not update the USERS file in their application if the
  134.   caller is returning to PCBoard.  Only if the caller hangs up inside the DOOR
  135.   and the DOOR modifies PCBOARD.SYS should the file be changed.
  136.  
  137.  
  138.   Note 2
  139.   ------
  140.   The "Allowed K-Bytes for Download" field specifies the number of K-bytes the
  141.   caller may download in a day according to the PWRD file and his security
  142.   level and his connect speed (if specified in the PWRD file).
  143.  
  144.   This is not the calculated number of K-bytes remaining.  To calculate the
  145.   number of bytes the caller may download you must multiply this number by 1024
  146.   and subtract from it the number of bytes th